 Copyright (c) 2005, 2012, Oracle and/or its affiliates. All rights reserved. 


           Oracle Multimedia JSP Photo Album Sample Application
           =====================================================

This file describes the steps required to build and run the Oracle Multimedia
JavaServer Pages(JSP) Photo Album sample application. This sample application 
is available after you install the Oracle Database Examples media, which 
you can download from Oracle Technology Network (OTN).


=============================================================================
Note:

For simplicity in demonstrating this feature, this example does not perform
the password management techniques that a deployed system normally uses. In a
production environment, follow the Oracle Database password management
guidelines, and disable any sample accounts. See Oracle Database Security
Guide for password management guidelines and other security recommendations. 
=============================================================================

                               Important
                               ---------

     JSP engines are not required to support access to the servlet 
     binary output stream. Therefore, not all JSP engines support the 
     delivery of multimedia data using the OrdHttpJspResponseHandler
     class. See the Oracle API documentation (also known as Javadoc) for 
     more information about the delivery of multimedia data from a JSP page.

Contents
========

    About the JSP Sample Application
    Configuring Your Servlet and JSP Container
        For Oracle Fusion Middleware 10gR3 Application Server 
            Requirements
            Setting up and Building the Sample Application
    Running the Sample Application
    Removing the Sample Application


About the JSP Sample Application
================================

The Oracle Multimedia JavaServer Pages (JSP) Photo Album sample application 
shows how to use the Oracle Multimedia Servlets and JSP Java Classes library 
to upload and retrieve multimedia data to and from a database. Users can 
access the JSPs to view the contents of the photo album (including thumbnail 
versions of each photograph), to view the full-size version of any 
photograph, and upload new photographs into the album.

The Oracle Multimedia JSP Photo Album sample application contains the 
following files:

  PhotoAlbumDBInfo.jsp
    A JSP that displays an HTML form that prompts users to enter the database 
    schema, password and the database connection string. 
    
    Users can choose one of these options for the database connection string.

    Option 1. A JDBC OCI driver specifying a SQL*Net service name.
       This option works on all platforms where an Oracle Database
       client is installed.  

    Option 2. A JDBC Thin driver specifying a host, port and Oracle 
       database SID.  This option works on all platforms and does not 
       require an Oracle Database client. 
    
    PhotoAlbumBean.java uses the input information to connect to the database,
    retrieve and upload photographs.

  PhotoAlbum.jsp
    A JSP that displays the contents of the photo album using an image
    tag <IMG SRC="PhotoAlbumMediaViewer.jsp?media=thumb&...> to display 
    the thumbnail images.

  PhotoAlbumEntryViewer.jsp
    A JSP that displays the full-size version of a photograph in the album
    using an image tag <IMG SRC="PhotoAlbumMediaViewer.jsp?media=image&..."> 
    to display the full-size image.

  PhotoAlbumMediaViewer.jsp
    A JSP that retrieves thumbnail or full-size images from the
    database and delivers them to the browser using the 
    OrdHttpResponseHandler class.

  PhotoAlbumUploadForm.jsp
    A JSP that displays an HTML form that allows users to upload new
    photographs into the album. In the action attribute of the form, 
    this JSP specifies the PhotoAlbumInsertPhoto.jsp page to process the 
    upload request.

  PhotoAlbumInsertPhoto.jsp
    A JSP that uses the OrdHttpUploadFormData class to parse the 
    multipart/form-data POST request containing the uploaded photograph. 
    It passes an OrdHttpUploadFile object to the PhotoAlbumBean class 
    to store the photograph in the database.

  PhotoAlbumBean.java
    A JavaBean used by the JSPs to access the database.

    The first call to the bean for a request causes it to allocate a 
    JDBC connection from a connection pool. Subsequent calls by the
    same request reuse the same connection. At the end of a request, 
    each JSP is responsible for calling the JavaBean to release the JDBC
    connection back to the pool. Each HTTP GET or POST request is 
    assigned its own JDBC connection from the pool to ensure that 
    multiple requests can be serviced concurrently.
  
    The selectTable() method selects all the rows in the photos table,
    while the selectRowById() method selects a specific row from the
    table. 
    
    The fetch() method fetches the next row from the result set. 
    
    The insertNewPhoto() method inserts a new row into the photos
    table.  It stores the uploaded photo as the full-size image using
    the loadImage() method in the OrdHttpUploadFile class, then 
    creates a thumbnail image using the processCopy() method in the 
    OrdImage class. 
    
    The methods setUsername(), setPassword() and setConnString() set 
    the connection information with the values that the user entered. 


Configuring Your Servlet and JSP Container
==========================================

This section describes how to configure your servlet and JSP container.

For Oracle Fusion Middleware 10gR3 Application Server 
=====================================================

Requirements
------------
This software must be installed to run the Oracle Multimedia JSP Photo 
Album sample application:

. Oracle Database with Oracle Multimedia.  

. Oracle Fusion Middleware 10gR3 Application Server(Oracle WebLogic Server 10.3)

Setting up and Building the Sample Application
--------------------------------------
In these instructions, <ORACLE_HOME> represents the Oracle Database home
directory, and <BEA_HOME> represents the default installation home 
directory for the the Oracle Fusion Middleware Application Server (Oracle 
WebLogic Server 10.3). Choose the appropriate home directory based on 
your specific installation, then follow these steps.

1) Choose a database schema under which you want to create the photo
   album table and the sequence. 

2) Create the photo album table and the sequence:

    The Oracle Multimedia JSP Photo Album sample application
    uses a sequence and this table definition:

      Name                  Null?     Type
      --------------------  --------  ----------------------------

      ID                    NOT NULL  NUMBER
      DESCRIPTION           NOT NULL  VARCHAR2(40)
      LOCATION                        VARCHAR2(40)
      IMAGE                           ORDSYS.ORDIMAGE
      THUMB                           ORDSYS.ORDIMAGE


    a. Start SQL*Plus and connect to the database with your user 
       name and password

       ->  SQL> connect <USER>[@<SERVICE>]
           Enter password: <password>

    b. Create the photo album table and sequence: 

       ->  SQL> @photostab.sql

3) Compile the photo album sample application JavaBean:

    PhotoAlbumBean.java depends on these Java class libraries: 

    a. The Oracle Multimedia Servlets and JSP Java class library 
       (ordhttp.jar) and the Oracle Multimedia Java classes library
       (ordim.jar), which are installed with Oracle Multimedia in the
       directory <ORACLE_HOME>/ord/jlib.

    b. The JDBC library and Java Servlet library that are installed 
       with Oracle Fusion Middleware Application Server.

    You can set the environment variable CLASSPATH for these libraries,
    or specify them in the command line. For example: 

    [on Linux/UNIX]
->  <BEA_HOME>/jdk160_05/bin/javac -d . -classpath .:<ORACLE_HOME>/ord/jlib/ordim.jar:<ORACLE_HOME>/ord/jlib/ordhttp.jar:<BEA_HOME>/wlserver_103/server/lib/ojdbc6.jar:<BEA_HOME>/modules/javax.servlet_1.0.0.0_2-5.jar PhotoAlbumBean.java

    [on Windows]
->  <BEA_HOME>\jdk160_05\bin\javac -d . -classpath .;<ORACLE_HOME>\ord\jlib\ordim.jar;<ORACLE_HOME>\ord\jlib\ordhttp.jar;<BEA_HOME>\wlserver_103\server\lib\ojdbc6.jar;<BEA_HOME>\modules\javax.servlet_1.0.0.0_2-5.jar PhotoAlbumBean.java

    Note: 
    
    To avoid compatibility issues, use the JDK that was installed with the
    Oracle Fusion Middleware Application Server. 

    After the compilation, the file PhotoAlbumBean.class is created in the  
    directory named "imjspdemo".

4) Copy the JSPs and images to a directory that is enabled to serve JSPs.

   a. Copy all the JSP files to this directory: 

      [on Linux/UNIX]
        <BEA_HOME>/wlserver_10.3/samples/server/examples/build/mainWebApp/ 

      [on Windows]
        <BEA_HOME>\wlserver_10.3\samples\server\examples\build\mainWebApp\
        
   b. Copy the image file error_qualifier.png to this directory (if it does 
      not exist, create it):

      [on Linux/UNIX]
      <BEA_HOME>/wlserver_10.3/samples/server/examples/build/mainWebApp/images/

      [on Windows]
      <BEA_HOME>\wlserver_10.3\samples\server\examples\build\mainWebApp\images\

5) Copy the resulting Java class file and Oracle Multimedia libraries into a 
   directory to be included in the environment variable CLASSPATH for your 
   servlet container. 

   a. Copy the directory "imjspdemo" that contains PhotoAlbumBean.class 
      file into this directory: 

      [on Linux/UNIX]
      <BEA_HOME>/wlserver_10.3/samples/server/examples/build/mainWebApp/WEB-INF/classes 

      [on Windows]
      <BEA_HOME>\wlserver_10.3\samples\server\examples\build\mainWebApp\WEB-INF\classes
        
   b. Copy the Oracle Multimedia libraries 

      [on Linux/UNIX]
        <ORACLE_HOME>/ord/jlib/ordhttp.jar
        <ORACLE_HOME>/ord/jlib/ordim.jar
 
      [on Windows]
        <ORACLE_HOME>\ord\jlib\ordhttp.jar
        <ORACLE_HOME>\ord\jlib\ordim.jar
 
   c. Place the copies in this directory (if it does not exist create it): 

      [on Linux/UNIX]
        <BEA_HOME>/wlserver_10.3/samples/server/examples/build/mainWebApp/WEB-INF/lib/ 
      [on Windows]
        <BEA_HOME>\wlserver_10.3\samples\server\examples\build\mainWebApp\WEB-INF\lib\

6) Restart the servlet container or the web server if you made any changes.


Running the Sample Application
==============================
To use the sample application, enter the URL of the JSP into the location bar 
of your web browser. For example:

[Default installation of Oracle Fusion Middleware 10gR3 Application Server]
  <HOST:PORT>/PhotoAlbumDBInfo.jsp

To login to the photo album, enter the database user name, the password and 
the connection string in this form: 

   JDBC thin driver 
   jdbc:oracle:thin:@<host>:<port>:<sid> 

   JDBC OCI driver
   jdbc:oracle:oci:@ 

Click Submit to display the contents of the photo album.

To upload a new photograph, click "Upload new photo". Then, enter 
a description of the photograph, the location where it was taken, 
and the name of the image file. Click "Upload new photo" to view 
the contents of the photo album, including the new photograph. 

Click on a thumbnail image to view the full-size version of any photograph. 
PhotoAlbum.jsp displays the text "[view image]" instead of a thumbnail 
image for images whose formats are not recognized by Oracle Multimedia. 

To connect to a different database or change the database schema, 
click "Change schema" to redirect to the login page (PhotoAlbumDBInfo.jsp). 

Removing the Sample Application
===============================
Use the script remove.sql to drop photo album schema objects from your 
database.

1)  Start SQL*Plus and connect to the database with your user name 
    and password

    ->  SQL> connect <USER>[@<SERVICE>]
        Enter password: <password>

2)  Drop the photo album table and the sequence 

    ->  SQL> @remove.sql

=====================
End of readme.txt


